ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee and ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr functions are very similar to
ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333NNNN)))) and ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr((((3333NNNN)))).... The functions cover all the
functionalities provided by the older ones, and provide better interface
to programmers. The functions require additional arguments, _a_f, and
_f_l_a_g_s, for specifying address family and operation mode. The additional
arguments allow programmer to get address for a nodename, for specific
address family (such as AF_INET or AF_INET6). The functions also require
an additional pointer argument, _e_r_r_o_r__n_u_m to return the appropriate error
code, to support thread safe error code returns.
The type and usage of the return value, struct hostent is described in
_g_e_t_h_o_s_t_b_y_n_a_m_e(_3_N).
For ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee,,,, the _n_a_m_e argument can be either a node name or a
numeric address string (i.e., a dotted-decimal IPv4 address or an IPv6
hex address). The _a_f argument specifies the address family, either
AF_INET or AF_INET6. The _f_l_a_g_s argument specifies the types of addresses
that are searched for, and the types of addresses that are returned. We
note that a special flags value of AI_DEFAULT (defined below) should
handle most applications. That is, porting simple applications to use
from having to call iiiinnnneeeetttt____ppppttttoooonnnn((((3333)))) to handle literal address strings. When
the _n_a_m_e argument is a literal address string, the _f_l_a_g_s argument is
always ignored.
There are four scenarios based on the type of literal address string and
the value of the _a_f argument. The two simple cases are when _n_a_m_e is a
dotted-decimal IPv4 address and _a_f equals AF_INET , or when _n_a_m_e is an
IPv6 hex address and _a_f equals AF_INET6. The members of the returned
hostent structure are: _h__n_a_m_e points to a copy of the _n_a_m_e argument,
_h__a_l_i_a_s_e_s is a NULL pointer, _h__a_d_d_r_t_y_p_e is a copy of the _a_f argument,
_h__l_e_n_g_t_h is either 4 (for AF_INET) or 16 (for AF_INET6), _h__a_d_d_r__l_i_s_t[_0]
is a pointer to the 4-byte or 16-byte binary address, and _h__a_d_d_r__l_i_s_t[_1]
is a NULL pointer.
When _n_a_m_e is a dotted-decimal IPv4 address and _a_f equals AF_INET6, and
AI_V4MAPPED is specified, an IPv4-mapped IPv6 address is returned:
_h__n_a_m_e points to an IPv6 hex address containing the IPv4-mapped IPv6
address, _h__a_l_i_a_s_e_s is a NULL pointer, _h__a_d_d_r_t_y_p_e is AF_INET6, _h__l_e_n_g_t_h is
16, _h__a_d_d_r__l_i_s_t[_0] is a pointer to the 16-byte binary address, and
_h__a_d_d_r__l_i_s_t[_1] is a NULL pointer.
It is an error when _n_a_m_e is an IPv6 hex address and _a_f equals AF_INET.
The function's return value is a NULL pointer and the value pointed to by
_e_r_r_o_r__n_u_m equals HOST_NOT_FOUND.
ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr takes almost the same argument as ggggeeeetttthhhhoooossssttttbbbbyyyyaaaaddddddddrrrr((((3333)))),,,, but
adds a pointer to return an error number. Additionally it takes care of
IPv4-mapped IPv6 addresses, and IPv4-compatible IPv6 addresses.
ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee and ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr dynamically allocate the structure to
be returned to the caller. ffffrrrreeeeeeeehhhhoooosssstttteeeennnntttt reclaims memory region allocated
and returned by ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee or ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr
ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee and ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr returns NULL on errors. The integer
values pointed to by _e_r_r_o_r__n_u_m may then be checked to see whether this is
a temporary failure or an invalid or unknown host. The meanings of each
error code are described in ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee((((3333))))....
ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee and ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr are documented in "Basic Socket
Interface Extensions for IPv6" (RFC2553).
BBBBUUUUGGGGSSSS
ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyynnnnaaaammmmeeee and ggggeeeettttiiiippppnnnnooooddddeeeebbbbyyyyaaaaddddddddrrrr do not handle scoped IPv6 address
properly. If you use these functions, your program will not be able to
handle scoped IPv6 addresses. For IPv6 address manipulation,
ggggeeeettttaaaaddddddddrrrriiiinnnnffffoooo((((3333)))) and ggggeeeettttnnnnaaaammmmeeeeiiiinnnnffffoooo((((3333)))) are recommended.
